Custom Views

Most drivers will suffice using the provided templates. Some advanced drivers however can benefit from creating their own views.

The front-end consists of .html files in the /drivers/<driver_id>/pair-folder. The name of the file is the view ID, as id described in /app.json.

The front-end has a few Homey-specific JavaScript functions available. They are documented here.

Back-end API

The socket property passed in onPair can control the front-end programmatically.

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {

  onPair( socket ) {
    // Show a specific view by ID
    socket.showView('my_view');

    // Show the next view
    socket.nextView();

    // Show the previous view
    socket.prevView();

    // Close the pair session
    socket.done();

    // Received when a view has changed
    socket.on('showView', ( viewId, callback ) => {
      callback();
      console.log('View: ' + viewId);
    });
  }

}

Front-end API

The following methods are available at the front-end to communicate with the back-end. The Homey object is globally available.

Emit an event

Homey.emit( String event, Mixed data, Function callback )

Emit an event to your app. The function called will be socket.on( String event ) in driver.js.

Example

/app.json

{
  "id": "com.athom.example",
  // ...
  "drivers": [
    {
      "id": "my_driver",
      // ...
      "pair": [
        {
          "id": "my_view"
        }
      ]
    }
  ]
}

/drivers/my_driver/pair/my_view.html

Homey.emit( 'my_event', { 'foo': 'bar' }, function( err, result ){
  console.log(result); // result is: Hello!
});

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {

  onPair( socket ) {
    socket.on('my_event', function( data, callback ) {
      // data is { 'foo': 'bar' }
      callback( null, 'Hello!' );
    });
  }

}

Receive an event

Homey.on( String event, Function callback )

Listen to a message from your app. You can trigger this function from your app by calling socket.emit().

Example

/drivers/my_driver/pair/start.html

Homey.on('hello', function( message, callback ){
  Homey.alert( message ); // Hello to you!
  callback( null, 'Hi!' ); // send something back, (err, data) style
});

/drivers/my_driver/driver.js

class MyDriver extends Homey.Driver {

  onPair( socket ) {
    socket.on('showView', (viewId, callback) => {
      callback();
      
      if( viewId === 'start' ) {
        socket.emit('hello', 'Hello to you!', function( err, data ){
	      console.log( data ) // Hi!
        });
      }
    });
  }

}

Set a Title

Homey.setTitle( String title )

Set the window's title.

Example

/drivers/my_driver/pair/start.html

Homey.setTitle( Homey.__('pair.title_searching') );

Show a View

Homey.showView( String viewId )

Navigate to another view. The parameter viewId should be an ID as specified in your app's /app.json.

/drivers/my_driver/pair/start.html

Homey.showView('list_devices');

Previous View

Homey.prevView()

Show the previous view.

Next View

Homey.nextView()

Show the next view.

Get the current view

Homey.getCurrentView()

Returns the current view ID.

Create a device

Homey.createDevice( Object device, Function callback )

Create a device with the properties in device.

The device object must at least contain the property data and may contain name, icon, class, capabilities, capabilitiesOptions, store and settings.

Example:

/drivers/my_driver/pair/start.html

Homey.createDevice({
  name: 'My Device',

  // the data object should contain only unique properties for the device. So a MAC address is good, an IP address is bad (can change over time)
  data: {
    id: 'abcdef',
  },

  // initial device settings that can be changed afterwards
  settings: {
    pincode: '1234',
  },

  // the store is dynamic and persistent storage for your device
  store: {},

}, function(err, result) {
  if( err ) return Homey.alert( err );
  Homey.done();
});

Get current zone

Homey.getZone( Function callback )

Get the Zone ID of the active Zone. The function callback returns ( err, zoneId ).

Get view options

Homey.getOptions( [String viewId], Function callback )

Get the options of a view, or the current view when viewId is omitted. The function callback returns ( err, viewOptions ).

View options may be added to a view by specifying an options object in the /app.json.

Set navigation close

Homey.setNavigationClose()

Remove all navigation buttons and show a single Close button.

Close the pair session

Homey.done()

Close the pairing window.

Alert dialog

Homey.alert( String message[, String icon], Function callback ) Show an alert dialog. The second parameter icon can be null, error, warning or info.

Confirm dialog

Homey.confirm( String message[, String icon], Function callback ) Show a confirm dialog. The second parameter icon can be null, error, warning or info.

The callback's 2nd argument will be true when the user pressed OK.

Popup

Homey.popup( String url ) Show a popup with a remote website.

Internationalisation

Homey.__( String key [, Object tokens] )

Translate a string programmatically. The first argument key is the name in your /locales/__language__.json. Use dots to get a sub-property, e.g. settings.title. The optional second argument tokens is an object with replacers. Read more about translations at Internationalization.

Show the loading overlay

Homey.showLoadingOverlay()

Shows the loading overlay.

Hide the loading overlay

Homey.hideLoadingOverlay()

Hides the loading overlay.

Get a view's store value

Homey.getViewStoreValue( String viewId, String key, Function callback )

Get's a view's store value. The callback is ( err, value ).

Set a view's store value

Homey.setViewStoreValue( String viewId, String key, Mixes value[, Function callback ])

Set a view's store value. The callback is ( err ).

Example

/drivers/my_driver/pair/start.html

var devicesArray = [
  {
    name: 'My Device',
    data: {
      id: 'abcd',
    }
  }
];
Homey.setViewStoreValue('add_devices', 'devices', devicesArray);